home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kprogress.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  11.8 KB  |  402 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1996 Martynas Kunigelis
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. /*****************************************************************************
  19. *                                                                            *
  20. *  KProgress -- progress indicator widget for KDE                            *
  21. *  Original QRangeControl-based version written by Martynas Kunigelis        *
  22. *  Current QProgressBar based version by Aaron Seigo                         *
  23. *                                                                            *
  24. *****************************************************************************/
  25.  
  26. #ifndef _KPROGRESS_H
  27. #define _KPROGRESS_H "$Id: kprogress.h 589356 2006-09-28 00:58:09Z jbaptiste $"
  28.  
  29. #include <qprogressbar.h>
  30. #include <kdialogbase.h>
  31.  
  32. /**
  33.  * @short A progress indicator widget.
  34.  *
  35.  * KProgress is derived from QProgressBar, so
  36.  * you can use all the methods from that class. The only real difference
  37.  * is that a signal is emitted on changes to the value and you do not need
  38.  * to subclass KProgress just to change the format of the indicator text.
  39.  *
  40.  * \b Details \n
  41.  *
  42.  * \image html kprogress.png "KDE Progress Widget"
  43.  *
  44.  * @author Aaron Seigo
  45.  */
  46. class KDEUI_EXPORT KProgress : public QProgressBar
  47. {
  48.   Q_OBJECT
  49.  
  50. public:
  51.   /**
  52.    * Construct a progress bar.
  53.    */
  54.   KProgress(QWidget *parent=0, const char *name=0, WFlags f = 0);
  55.  
  56.   /**
  57.    * Construct a progress bar with a total number of steps.
  58.    * The totalSteps is the total number of steps that need to be completed for the operation which this progress
  59.    * bar represents. For example, if the operation is to examine 50 files, this value would be 50. Before examining
  60.    * the first file, call setProgress(0); call setProgress(50) after examining the last file.
  61.    */
  62.   KProgress(int totalSteps, QWidget *parent=0, const char *name=0, WFlags f = 0);
  63.  
  64.   /**
  65.    * Destruct the progress bar.
  66.    */
  67.   ~KProgress();
  68.  
  69.   /**
  70.    * If this is set to @p true, the progress text will be displayed.
  71.    *
  72.    */
  73.   void setTextEnabled(bool);
  74.  
  75.   /**
  76.    * @deprecated Retrieves the current status, use progress() instead
  77.    *
  78.    * @see setValue()
  79.    */
  80.   // ### Remove this KDE 4.0
  81.   int value() const KDE_DEPRECATED;
  82.  
  83.   /**
  84.    * Returns @p true if progress text will be displayed,
  85.    * @p false otherwise.
  86.    *
  87.    * @see setFormat()
  88.    */
  89.   bool textEnabled() const;
  90.  
  91.   /**
  92.    * Retrieve the current format for printing status text.
  93.    * @see setFormat()
  94.    */
  95.   QString format() const;
  96.  
  97.   /**
  98.    * @deprecated but kept for source compatibility with KDE2's KProgress.
  99.    * Use setTotalSteps() instead
  100.    */
  101.   // ### Remove this KDE 4.0
  102.   void setRange(int min, int max) KDE_DEPRECATED;
  103.  
  104.   /**
  105.    * @deprecated Use totalSteps() instead
  106.    */
  107.   // ### Remove this KDE 4.0
  108.   int maxValue() KDE_DEPRECATED;
  109.  
  110. public slots:
  111.  
  112.   /**
  113.    * Set the format of the text to use to display status.
  114.    *
  115.    * The default format is "%p%" (which looks like "42%".)
  116.    *
  117.    * Note: Setting the format to anything other then "%p%" will force centerIndicator to true,
  118.    * since it's often impossible to layout a progressbar with a more general format with the
  119.    * indicator string anywhere else.
  120.    *
  121.    * @param format "%p" is replaced by percentage done, "%v" is replaced by actual
  122.    * value, "%m" is replaced by the maximum value.
  123.    */
  124.   void setFormat(const QString & format);
  125.  
  126.   /**
  127.     * Set the current total number of steps in the action that the progress bar
  128.     * is representing.
  129.     */
  130.   void setTotalSteps(int totalSteps);
  131.  
  132.   /**
  133.     * Set the current value of the progress bar to @p progress.
  134.     */
  135.   virtual void setProgress(int progress);
  136.  
  137.   /**
  138.     * @deprecated Use setProgress(int) instead
  139.     */
  140.   // ### Remove this KDE 4.0
  141.   void setValue(int progress);
  142.  
  143.   /**
  144.    * Advance the progress bar by @p offset.
  145.    *
  146.    * This method is
  147.    * provided for convenience and is equivalent with
  148.    * setProgress(progress()+offset).
  149.    */
  150.   virtual void advance(int offset);
  151.  
  152. signals:
  153.   /**
  154.    * Emitted when the state of the progress bar changes.
  155.    */
  156.   void percentageChanged(int);
  157.  
  158. protected:
  159.   virtual bool setIndicator(QString & indicator, int progress, int totalSteps);
  160.  
  161. private:
  162.   QString   mFormat;
  163.  
  164. protected:
  165.   virtual void virtual_hook( int id, void* data );
  166. private:
  167.   class KProgressPrivate;
  168.   KProgressPrivate *d;
  169. };
  170.  
  171. /**
  172.  * KProgressDialog provides a dialog with a text label, a progress bar
  173.  * and an optional cancel button with a KDE look 'n feel.
  174.  *
  175.  * Since knowing how long it can take to complete an action and it is
  176.  * undesirable to show a dialog for a split second before hiding it,
  177.  * there are a few ways to control the timing behavior of KProgressDialog.
  178.  * There is a time out that can be set before showing the dialog as well
  179.  * as an option to autohide or keep displaying the dialog once complete.
  180.  *
  181.  * All the functionality of KProgress is available through direct access
  182.  * to the progress bar widget via progressBar();
  183.  *
  184.  * @short A dialog with a progress bar
  185.  * @author Aaron J. Seigo
  186.  */
  187. class KDEUI_EXPORT KProgressDialog : public KDialogBase
  188. {
  189.     Q_OBJECT
  190.  
  191.     public:
  192.         /**
  193.          * Constructs a KProgressDialog
  194.          *
  195.          * @param parent Parent of the widget
  196.          * @param name Widget name
  197.          * @param caption Text to display in window title bar
  198.          * @param text Text to display in the dialog
  199.          * @param modal Set to true to make the dialog modal
  200.          */
  201.         KProgressDialog(QWidget* parent = 0, const char* name = 0,
  202.                         const QString& caption = QString::null,
  203.                         const QString& text = QString::null,
  204.                         bool modal = false);
  205.  
  206.         /**
  207.          * Destructor
  208.          */
  209.         ~KProgressDialog();
  210.  
  211.         /**
  212.          * Returns the KProgress used in this dialog.
  213.          * To set the number of steps or other progress bar related
  214.          * settings, access the KProgress object directly via this method.
  215.          */
  216.         KProgress* progressBar();
  217.  
  218.         /**
  219.          * Returns the KProgress used in this dialog.
  220.          * To set the number of steps or other progress bar related
  221.          * settings, access the KProgress object directly via this method.
  222.          */
  223.         const KProgress* progressBar() const;
  224.  
  225.         /**
  226.          * Sets the text in the dialog
  227.          *
  228.          * @param text the text to display
  229.          */
  230.         void    setLabel(const QString & text);
  231.  
  232.         /**
  233.          * Returns the current dialog text
  234.          * @deprecated
  235.          */
  236.         // ### Remove this KDE 4.0
  237.         QString labelText() KDE_DEPRECATED;
  238.  
  239.         /**
  240.          * Returns the current dialog text
  241.          */
  242.         QString labelText() const;
  243.  
  244.         /**
  245.          * Sets whether or not the user can cancel the process.
  246.          * If the dialog is cancellable, the Cancel button will be shown
  247.          * and the user can close the window using the window decorations.
  248.          * If the process is not (or should not be) interuptable,
  249.          * set the dialog to be modal and not cancellable.
  250.          *
  251.          * @param allowCancel Set to true to make the dialog non-closable
  252.          */
  253.         void setAllowCancel(bool allowCancel);
  254.  
  255.         /**
  256.          * Returns true if the dialog can be canceled, false otherwise
  257.          * @deprecated
  258.          */
  259.         // ### Remove this KDE 4.0
  260.         bool allowCancel() KDE_DEPRECATED;
  261.  
  262.         /**
  263.          * Returns true if the dialog can be canceled, false otherwise
  264.          */
  265.         bool allowCancel() const;
  266.  
  267.         /**
  268.          * Sets whether the cancel button is visible. setAllowCancel(false)
  269.          * implies showCancelButton(false)
  270.          *
  271.          * @param show Whether or not the cancel button should be shown
  272.          */
  273.         void showCancelButton(bool show);
  274.  
  275.         /**
  276.          * Sets whether the dialog should close automagically when
  277.          * all the steps in the KProgress have been completed.
  278.          */
  279.         void setAutoClose(bool close);
  280.  
  281.         /**
  282.          * Returns true if the dialog will close upon completion,
  283.          * or false otherwise
  284.          */
  285.         // ### Remove this KDE 4.0
  286.         bool autoClose();
  287.  
  288.         /**
  289.          * Returns true if the dialog will close upon completion,
  290.          * or false otherwise
  291.          */
  292.         bool autoClose() const;
  293.  
  294.         /**
  295.          * Sets whether the dialog should reset the KProgress dialog
  296.          * back to 0 steps compelete when all steps have been completed.
  297.          * This is useful for KProgressDialogs that will be reused.
  298.          */
  299.         void setAutoReset(bool autoReset);
  300.  
  301.         /**
  302.          * Returns true if the KProgress widget will be reset
  303.          * upon completion, or false otherwise
  304.          */
  305.         // ### Remove this KDE 4.0
  306.         bool autoReset();
  307.  
  308.         /**
  309.          * Returns true if the KProgress widget will be reset
  310.          * upon completion, or false otherwise
  311.          */
  312.         bool autoReset() const;
  313.  
  314.         /**
  315.          * Returns true if the dialog was closed or canceled
  316.          * before completion. If the dialog is not cancellable
  317.          * it will always return false.
  318.          */
  319.         // ### Remove this KDE 4.0
  320.         bool wasCancelled();
  321.  
  322.         /**
  323.          * Returns true if the dialog was closed or canceled
  324.          * before completion. If the dialog is not cancellable
  325.          * it will always return false.
  326.          */
  327.         bool wasCancelled() const;
  328.  
  329.         /**
  330.          * Ignores the last cancel action if the cancel button was 
  331.          * pressed. Useful for kdialog when combined with a KMessageBox
  332.          * to display a message like "Are you sure you want to cancel?" 
  333.      * @since 3.5.5
  334.          */
  335.         void ignoreCancel();
  336.  
  337.         /**
  338.          * Sets the text to appear on the cancel button.
  339.          */
  340.         void setButtonText(const QString&);
  341.  
  342.         /**
  343.          * Returns the text on the cancel button
  344.          * @deprecated
  345.          */
  346.         // ### Remove this KDE 4.0
  347.         QString buttonText() KDE_DEPRECATED;
  348.  
  349.         /**
  350.          * Returns the text on the cancel button
  351.          */
  352.         QString buttonText() const;
  353.  
  354.         /**
  355.          * Set the minimum number of milliseconds to wait before
  356.          * actually showing the dialog
  357.          */
  358.         void setMinimumDuration(int ms);
  359.  
  360.         /**
  361.          * Returns the wait duration in milliseconds
  362.          * @deprecated
  363.          */
  364.         // ### Remove this KDE 4.0
  365.         int  minimumDuration() KDE_DEPRECATED;
  366.  
  367.         /**
  368.          * Returns the wait duration in milliseconds
  369.          */
  370.         int  minimumDuration() const;
  371.  
  372.      /**
  373.      * Reimplemented for internal reasons, the API is not affected.
  374.      */
  375.         virtual void show();
  376.  
  377.     protected slots:
  378.         void slotAutoShow();
  379.         void slotAutoActions(int percentage);
  380.         void slotCancel();
  381.  
  382.     private:
  383.         // ### Move these member variables to d in KDE 4.0
  384.         bool       mAutoClose;
  385.         bool       mAutoReset;
  386.         bool       mCancelled;
  387.         bool       mAllowCancel;
  388.         bool       mShown;
  389.         QString    mCancelText;
  390.         QLabel*    mLabel;
  391.         KProgress* mProgressBar;
  392.         QTimer*    mShowTimer;
  393.         int        mMinDuration;
  394.     protected:
  395.     virtual void virtual_hook( int id, void* data );
  396.     private:
  397.         struct KProgressDialogPrivate;
  398.         KProgressDialogPrivate *d;
  399. };
  400.  
  401. #endif
  402.